/*
 * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.nio.channels;

import java.net.SocketOption;
import java.net.SocketAddress;
import java.util.Set;
import java.io.IOException;

/**
 * 到网络套接字的通道。
 *
 * <p> 实现此接口的通道是到网络套接字的通道。
 * bind方法用于将套接字绑定到本地SocketAddress，getLocalAddress方法返回套接字绑定到的地址，setOption和getOption方法用于设置和查询套接字选项。
 * 该接口的实现应该指定它所支持的套接字选项。
 *
 * <p> bind和setOption方法如果没有返回值，则被指定为返回调用它们的网络通道。
 * 这允许方法调用成链。该接口的实现应该指定返回类型，从而实现类的方法引用可以成链。
 *
 * @since 1.7
 */

public interface NetworkChannel
    extends Channel
{
    /**
     * 将通道的套接字绑定到本地地址。
     *
     * <p> 此方法用于建立套接字与本地地址之间的关联。
     * 一旦建立了关联，套接字就会一直绑定，直到通道关闭。
     * 如果local参数的值为null，那么套接字将被绑定到一个自动分配的地址。
     *
     * @param   local
     *          The address to bind the socket, or {@code null} to bind the socket
     *          to an automatically assigned socket address
     *
     * @return  This channel
     *
     * @throws  AlreadyBoundException
     *          If the socket is already bound
     * @throws  UnsupportedAddressTypeException
     *          If the type of the given address is not supported
     * @throws  ClosedChannelException
     *          If the channel is closed
     * @throws  IOException
     *          If some other I/O error occurs
     * @throws  SecurityException
     *          If a security manager is installed and it denies an unspecified
     *          permission. An implementation of this interface should specify
     *          any required permissions.
     *
     * @see #getLocalAddress
     */
    NetworkChannel bind(SocketAddress local) throws IOException;

    /**
     * 返回此通道的套接字绑定到的套接字地址。
     *
     * <p> 如果通道被绑定到Internet Protocol 套接字地址，那么该方法的返回值类型为java.net.InetSocketAddress。
     *
     * @return  The socket address that the socket is bound to, or {@code null}
     *          if the channel's socket is not bound
     *
     * @throws  ClosedChannelException
     *          If the channel is closed
     * @throws  IOException
     *          If an I/O error occurs
     */
    SocketAddress getLocalAddress() throws IOException;

    /**
     * 设置套接字选项的值。
     *
     * @param   <T>
     *          The type of the socket option value
     * @param   name
     *          The socket option
     * @param   value
     *          The value of the socket option. A value of {@code null} may be
     *          a valid value for some socket options.
     *
     * @return  This channel
     *
     * @throws  UnsupportedOperationException
     *          If the socket option is not supported by this channel
     * @throws  IllegalArgumentException
     *          If the value is not a valid value for this socket option
     * @throws  ClosedChannelException
     *          If this channel is closed
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @see java.net.StandardSocketOptions
     */
    <T> NetworkChannel setOption(SocketOption<T> name, T value) throws IOException;

    /**
     * 返回套接字选项的值
     *
     * @param   <T>
     *          The type of the socket option value
     * @param   name
     *          The socket option
     *
     * @return  The value of the socket option. A value of {@code null} may be
     *          a valid value for some socket options.
     *
     * @throws  UnsupportedOperationException
     *          If the socket option is not supported by this channel
     * @throws  ClosedChannelException
     *          If this channel is closed
     * @throws  IOException
     *          If an I/O error occurs
     *
     * @see java.net.StandardSocketOptions
     */
    <T> T getOption(SocketOption<T> name) throws IOException;

    /**
     * 返回此通道支持的套接字选项的集合。
     *
     * <p> 即使通道已经关闭，这个方法也会继续返回选项集
     *
     * @return  A set of the socket options supported by this channel
     */
    Set<SocketOption<?>> supportedOptions();
}
